---
title: uni-app x 专题
description: 面向用户的实战手册，10 分钟完成 Tailwind CSS 在 uni-app x 的跨端集成与开发。
---

import Link from '@docusaurus/Link'
import TailwindcssLogo from '../../../assets/logo.png'

# uni-app x 专题

<div
  className="
    not-prose relative mt-2 flex items-center gap-4 rounded-2xl border
    border-emerald-200/70 bg-gradient-to-br from-white via-emerald-50 to-emerald-100
    p-5 shadow-[0_14px_40px_rgba(16,185,129,0.18)]
    dark:border-emerald-900/60 dark:from-emerald-950/50 dark:via-emerald-950/30 dark:to-emerald-900/20
    dark:shadow-[0_18px_40px_rgba(16,185,129,0.3)]
  "
>
  <img className="h-16 sm:h-20" src={TailwindcssLogo} alt="Tailwind CSS" />
  <i className="icon-[mdi--link] text-3xl text-emerald-500 dark:text-emerald-300" />
  <img className="h-16 sm:h-20" src="/img/uni-app-x-logo.ico" alt="uni-app x" />
  <div className="ml-auto hidden text-right sm:block">
    <div className="text-xs font-medium text-emerald-700/80 dark:text-emerald-200/80">跨端原子化样式方案</div>
    <div className="text-base font-semibold text-emerald-800 dark:text-emerald-200">Tailwind CSS × uni-app x</div>
  </div>
</div>

<div className="not-prose mt-4 grid grid-cols-1 gap-3 sm:auto-cols-max sm:grid-flow-col">
  <a className="docs-cta-primary" href="https://github.com/icebreaker-template/uni-app-x-hbuilderx" target="_blank" rel="noopener noreferrer">
    <i className="icon-[mdi--rocket-launch] text-xl" />
    一键使用模板项目（推荐）
  </a>
  <a className="docs-cta-secondary" href="/docs/uni-app-x/install">
    <i className="icon-[mdi--playlist-check] text-lg opacity-80" />
    或者按步骤手动集成
  </a>
</div>

## 这篇文档适合谁

- 想在 uni-app x 项目里使用 Tailwind CSS 的开发者
- 需要一套能同时覆盖 Web/小程序/Android/iOS/鸿蒙 的原子化样式方案
- 希望以最少的改动尽快起步，并有清晰的后续扩展路线

## 你将收获什么

- 完整的从 0 到 1 集成流程（含运行与验证）
- 可复用的模板项目与配置清单
- 多端开发的实践建议与避坑说明

:::info 支持范围
当前跨端集成仅支持 `tailwindcss@3.x`。  
`tailwindcss@4.x` 生成的 CSS 依赖诸多现代特性，`uni-app x` 暂未全部覆盖，故不建议在该场景使用 v4。
:::

## 最快开始

- 想最快跑起来：点击上方「一键使用模板项目」，按 README 步骤打开 HBuilderX 运行即可
- 想了解每一步：前往「手动集成」教程 → <Link to="/docs/uni-app-x/install">快速集成</Link>

## 开发建议（从用户出发）

- 推荐编辑器协作：用 VS Code 写代码，用 HBuilderX 负责运行与构建
- 首选 Android 端调试：CSS 兼容度一般是 Web > 小程序 > App（Android/iOS/鸿蒙）。先用 Android 模拟器打通路径，跨端成本最低
- 组件语义注意：原生 App 端文字需放在 `<text>` 标签，且文本样式需要直接作用在该元素上
- 渐进增强：若某些样式在 App 端受限，优先保证 Android 端体验，再按需做条件编译适配小程序/Web

## 为什么推荐先用 Android

1) 原生端样式约束更严格，例如文本必须使用 `<text>`，许多 CSS 特性仍在补齐中  
2) 如果你的页面在 Android 端无告警、展示正确，迁移到小程序与 Web 的心智负担会小很多  
3) iOS/鸿蒙的调试门槛更高（设备/系统要求），多数团队以 Android 作为优先目标更务实

## 常见问题

### VS Code 对 uvue/uts 的高亮与跳转

安装官方语言服务插件：  
- ID: dcloud-ide.hbuilderx-language-services  
- 说明: 支持 uni-app x 项目的提示、悬浮、转到定义、查找引用、校验等  
- 链接: https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services

### Tailwind CSS 智能提示

VS Code 原生不识别 `uvue/uts`，建议为 Tailwind 扩展加上语言映射。在项目根目录创建 `.vscode/settings.json`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}
```

### 运行方式

目前 `uni-app x` 尚无 CLI，需通过 HBuilderX 进行运行与构建。  
建议配合 Android 模拟器进行开发调试。

## 接下来

- 跟着步骤手动完成集成：<Link to="/docs/uni-app-x/install">快速集成</Link>  
- 直接基于模板起步：<Link to="https://github.com/icebreaker-template/uni-app-x-hbuilderx">uni-app x + Tailwind 模板（HBuilderX）</Link>
